<!DOCTYPE html>

































































<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="shortcut icon" type="image/x-icon" href="../../../favicon.ico" />
<title>App Widgets | Android Developers</title>
<link href="../../../assets/android-developer-docs-devguide.css" rel="stylesheet" type="text/css" />
<script src="../../../assets/search_autocomplete.js" type="text/javascript"></script>
<script src="../../../assets/jquery-resizable.min.js" type="text/javascript"></script>
<script src="../../../assets/android-developer-docs.js" type="text/javascript"></script>
<script src="../../../assets/prettify.js" type="text/javascript"></script>
<script type="text/javascript">
  setToRoot("../../../");
</script>
<noscript>
  <style type="text/css">
    html,body{overflow:auto;}
    #body-content{position:relative; top:0;}
    #doc-content{overflow:visible;border-left:3px solid #666;}
    #side-nav{padding:0;}
    #side-nav .toggle-list ul {display:block;}
    #resize-packages-nav{border-bottom:3px solid #666;}
  </style>
</noscript>
</head>
<body class="gc-documentation">

  <div id="header">
      <div id="headerLeft">
          <a href="../../../index.html" tabindex="-1"><img
              src="../../../assets/images/bg_logo.png" alt="Android Developers" /></a>
          <ul id="header-tabs" class="guide">
    
	<li id="home-link"><a href="../../../offline.html">
	
		<span class="en">Home</span>
		<span style="display:none" class="de">Startseite</span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
		<span style="display:none" class="ja">ホーム</span>
		<span style="display:none" class="zh-CN">主页</span>
		<span style="display:none" class="zh-TW">首頁</span>
	
	</a></li>
	<li id="sdk-link"><a href="../../../sdk/index.html">
		<span class="en">SDK</span>
	</a></li>
	<li id="guide-link"><a href="../../../guide/index.html" onClick="return loadLast('guide')">
	
		<span class="en">Dev Guide</span>
		<span style="display:none" class="de">Handbuch</span>
		<span style="display:none" class="es">Guía</span>
		<span style="display:none" class="fr">Guide</span>
		<span style="display:none" class="it">Guida</span>
		<span style="display:none" class="ja">開発ガイド</span>
		<span style="display:none" class="zh-CN">开发人员指南</span>
		<span style="display:none" class="zh-TW">開發指南</span>
	
	</a></li>
	<li id="reference-link"><a href="../../../reference/packages.html" onClick="return loadLast('reference')">
	
		<span class="en">Reference</span>
		<span style="display:none" class="de">Referenz</span>
		<span style="display:none" class="es">Referencia</span>
		<span style="display:none" class="fr">Référence</span>
		<span style="display:none" class="it">Riferimento</span>
		<span style="display:none" class="ja">リファレンス</span>
		<span style="display:none" class="zh-CN">参考</span>
		<span style="display:none" class="zh-TW">參考資料</span>
	
	</a></li>
	<li id="resources-link"><a href="../../../resources/index.html" onClick="return loadLast('resources')">
	
		<span class="en">Resources</span>
		<span style="display:none" class="de"></span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
    		<span style="display:none" class="ja"></span>
		<span style="display:none" class="zh-CN"></span>
		<span style="display:none" class="zh-TW"></span>
	
	</a></li>
	<li id="videos-link"><a href="../../../videos/index.html" onClick="return loadLast('videos')">
	
		<span class="en">Videos</span>
		<span style="display:none" class="de"></span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
		<span style="display:none" class="ja">ビデオ</span>
		<span style="display:none" class="zh-CN"></span>
		<span style="display:none" class="zh-TW"></span>
	
	</a></li>
	<li><a href="http://android-developers.blogspot.com" onClick="return requestAppendHL(this.href)">
	
		<span class="en">Blog</span>
		<span style="display:none" class="de"></span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
		<span style="display:none" class="ja">ブログ</span>
		<span style="display:none" class="zh-CN">博客</span>
		<span style="display:none" class="zh-TW">網誌</span>
	
	</a></li>


     
</ul>
     
      </div>
      <div id="headerRight">
          <div id="headerLinks">
          
          <a href="http://www.android.com">Android.com</a>
          </div>
  <div id="search" >
      <div id="searchForm">
          <form accept-charset="utf-8" class="gsc-search-box" 
                onsubmit="return submit_search()">
            <table class="gsc-search-box" cellpadding="0" cellspacing="0"><tbody>
                <tr>
                  <td class="gsc-input">
                    <input id="search_autocomplete" class="gsc-input" type="text" size="33" autocomplete="off"
                      title="search developer docs" name="q"
                      value="search developer docs"
                      onFocus="search_focus_changed(this, true)"
                      onBlur="search_focus_changed(this, false)"
                      onkeydown="return search_changed(event, true, '../../../')"
                      onkeyup="return search_changed(event, false, '../../../')" />
                  <div id="search_filtered_div" class="no-display">
                      <table id="search_filtered" cellspacing=0>
                      </table>
                  </div>
                  </td>
                  <td class="gsc-search-button">
                    <input type="submit" value="Search" title="search" id="search-button" class="gsc-search-button" />
                  </td>
                  <td class="gsc-clear-button">
                    <div title="clear results" class="gsc-clear-button">&nbsp;</div>
                  </td>
                </tr></tbody>
              </table>
          </form>
      </div><!-- searchForm -->
  </div><!-- search -->
      </div><!-- headerRight -->
      <script type="text/javascript">
        <!--  
        changeTabLang(getLangPref());
        //-->
      </script>
  </div><!-- header -->

  <div class="g-section g-tpl-240" id="body-content">
    <div class="g-unit g-first" id="side-nav">
      <div id="devdoc-nav">
<ul>

  <li>
    <h2><span class="en">Android Basics</span>
        <span class="de" style="display:none">Einführung in Android</span>
        <span class="es" style="display:none">Información básica sobre Android</span>
        <span class="fr" style="display:none">Présentation d'Android</span>
        <span class="it" style="display:none">Nozioni di base su Android</span>
        <span class="ja" style="display:none">Android の基本</span>
        <span class="zh-CN" style="display:none">Android 基础知识</span>
        <span class="zh-TW" style="display:none">Android 簡介</span>
    </h2>
    <ul>
      <li><a href="../../../guide/basics/what-is-android.html">
        <span class="en">What Is Android?</span>
        <span class="de" style="display:none">Was ist Android?</span>
        <span class="es" style="display:none">¿Qué es Android?</span>
        <span class="fr" style="display:none">Qu'est-ce qu'Android&nbsp;?</span>
        <span class="it" style="display:none">Che cos'è Android?</span>
        <span class="ja" style="display:none">Android とは</span>
        <span class="zh-CN" style="display:none">Android 是什么？</span>
        <span class="zh-TW" style="display:none">什麼是 Android？</span>
          </a></li>
      <li><a href="../../../guide/topics/fundamentals.html">
        <span class="en">Application Fundamentals</span>
        <span class="de" style="display:none">Anwendungsgrundlagen</span>
        <span class="es" style="display:none">Fundamentos de las aplicaciones</span>
        <span class="fr" style="display:none">Principes de base des applications</span>
        <span class="it" style="display:none">Concetti fondamentali sulle applicazioni</span>
        <span class="ja" style="display:none">開発の基礎</span>
        <span class="zh-CN" style="display:none">应用程序基础</span>
        <span class="zh-TW" style="display:none">應用程式基本原理</span>
      </a></li>

  <!--  <li><a style="color:gray;">The Android SDK</a></li> -->
  <!--  <li><a style="color:gray;">Walkthrough for Developers</a></li> -->
      <!-- quick overview of what it's like to develop on Android -->
    </ul>
  </li>

  <li>
    <h2>
      <span class="en">Framework Topics</span>
      <span class="de" style="display:none">Framework-Themen</span>
      <span class="es" style="display:none">Temas sobre el framework</span>
      <span class="fr" style="display:none">Thèmes relatifs au framework</span>
      <span class="it" style="display:none">Argomenti relativi al framework</span>
      <span class="ja" style="display:none">フレームワーク トピック</span>
      <span class="zh-CN" style="display:none">框架主题</span>
      <span class="zh-TW" style="display:none">架構主題</span>
    </h2>
    <ul>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/fundamentals/activities.html">
          <span class="en">Activities</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/topics/fundamentals/fragments.html">
            <span class="en">Fragments</span>
          </a></li>
          <li><a href="../../../guide/topics/fundamentals/loaders.html">
            <span class="en">Loaders</span>
          </a></li>
          <li><a href="../../../guide/topics/fundamentals/tasks-and-back-stack.html">
            <span class="en">Tasks and Back Stack</span></a></li>
        </ul>
      </li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/fundamentals/services.html">
          <span class="en">Services</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/topics/fundamentals/bound-services.html">
            <span class="en">Bound Services</span>
          </a></li>
        </ul>
      </li>
      <li><a href="../../../guide/topics/providers/content-providers.html">
            <span class="en">Content Providers</span>
          </a></li>
      <li><a href="../../../guide/topics/intents/intents-filters.html">
            <span class="en">Intents and Intent Filters</span>
          </a></li>
      <li><a href="../../../guide/topics/fundamentals/processes-and-threads.html">
            <span class="en">Processes and Threads</span>
          </a></li>
    </ul>


    <ul>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/ui/index.html">
            <span class="en">User Interface</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/topics/ui/declaring-layout.html">
               <span class="en">XML Layouts</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/ui-events.html">
                <span class="en">Input Events</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/menus.html">
               <span class="en">Menus</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/actionbar.html">
               <span class="en">Action Bar</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/dialogs.html">
                <span class="en">Dialogs</span>
              </a></li>
          <li class="toggle-list">
            <div><a href="../../../guide/topics/ui/notifiers/index.html">
                <span class="en">Notifications</span>
            </a></div>
            <ul>
              <li><a href="../../../guide/topics/ui/notifiers/toasts.html">
                <span class="en">Toast Notifications</span>
              </a></li>
              <li><a href="../../../guide/topics/ui/notifiers/notifications.html">
                <span class="en">Status Bar Notifications</span>
              </a></li>
            </ul>
          </li>
          <li><a href="../../../guide/topics/ui/drag-drop.html">
                <span class="en">Drag and Drop</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/themes.html">
                <span class="en">Styles and Themes</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/custom-components.html">
                <span class="en">Custom Components</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/binding.html">
                <span class="en">Binding to Data with AdapterView</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/layout-objects.html">
                <span class="en">Common Layout Objects</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/how-android-draws.html">
                <span class="en">How Android Draws Views</span>
              </a></li>
        </ul>
      </li><!-- end of User Interface -->

      <li class="toggle-list">
        <div><a href="../../../guide/topics/resources/index.html">
               <span class="en">Application Resources</span>
             </a></div>
        <ul>
          <li><a href="../../../guide/topics/resources/providing-resources.html">
                <span class="en">Providing Resources</span>
              </a></li>
          <li><a href="../../../guide/topics/resources/accessing-resources.html">
                <span class="en">Accessing Resources</span>
              </a></li>
          <li><a href="../../../guide/topics/resources/runtime-changes.html">
                <span class="en">Handling Runtime Changes</span>
              </a></li>
          <li><a href="../../../guide/topics/resources/localization.html">
                <span class="en">Localization</span>
              </a></li>
          <li class="toggle-list">
            <div><a href="../../../guide/topics/resources/available-resources.html">
              <span class="en">Resource Types</span>
            </a></div>
            <ul>
              <li><a href="../../../guide/topics/resources/animation-resource.html">Animation</a></li>
              <li><a href="../../../guide/topics/resources/color-list-resource.html">Color State List</a></li>
              <li><a href="../../../guide/topics/resources/drawable-resource.html">Drawable</a></li>
              <li><a href="../../../guide/topics/resources/layout-resource.html">Layout</a></li>
              <li><a href="../../../guide/topics/resources/menu-resource.html">Menu</a></li>
              <li><a href="../../../guide/topics/resources/string-resource.html">String</a></li>
              <li><a href="../../../guide/topics/resources/style-resource.html">Style</a></li>
              <li><a href="../../../guide/topics/resources/more-resources.html">More Types</a></li>
            </ul>
          </li><!-- end of resource types -->
        </ul>
      </li><!-- end of app resources -->
      <li class="toggle-list">
        <div><a href="../../../guide/topics/data/data-storage.html">
            <span class="en">Data Storage</span>
          </a></div>
          <ul>
            <li><a href="../../../guide/topics/data/backup.html">
                <span class="en">Data Backup</span>
              </a>
            </li>
          </ul>
      </li>
      <li><a href="../../../guide/topics/security/security.html">
            <span class="en">Security and Permissions</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/manifest/manifest-intro.html">
          <span class="en">The AndroidManifest.xml File</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/topics/manifest/action-element.html">&lt;action&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/application-element.html">&lt;application&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/category-element.html">&lt;category&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/compatible-screens-element.html">&lt;compatible-screens&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/data-element.html">&lt;data&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/instrumentation-element.html">&lt;instrumentation&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/path-permission-element.html">&lt;path-permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/service-element.html">&lt;service&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></li><!-- ##api level 4## -->
          <li><a href="../../../guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></li> <!-- ##api level 4## -->
          <li><a href="../../../guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></li>
        </ul>
      </li><!-- end of the manifest file -->
    </ul>

    <ul>
    <li class="toggle-list">
        <div><a href="../../../guide/topics/graphics/index.html">
            <span class="en">Graphics</span>
          </a><span class="new-child">new!</span></div>
        <ul>
          <li><a href="../../../guide/topics/graphics/2d-graphics.html">
              <span class="en">Canvas and Drawables</span></a></li>
          <li><a href="../../../guide/topics/graphics/hardware-accel.html">
              <span class="en">Hardware Acceleration</span></a>
            <span class="new">new!</span></li>
          <li><a href="../../../guide/topics/graphics/opengl.html">
              <span class="en">OpenGL</span>
            </a><span class="new">updated</span></li>
        </ul>
      </li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/graphics/animation.html">
            <span class="en">Animation</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/topics/graphics/prop-animation.html">
              <span class="en">Property Animation</span></a></li>
          <li><a href="../../../guide/topics/graphics/view-animation.html">
              <span class="en">View Animation</span></a></li>
          <li><a href="../../../guide/topics/graphics/drawable-animation.html">
              <span class="en">Drawable Animation</span></a></li>
        </ul>
      </li>
      <li class="toggle-list">
	        <div><a href="../../../guide/topics/renderscript/index.html">
	            <span class="en">RenderScript</span>
	          </a></div>
	        <ul>
	          <li><a href="../../../guide/topics/renderscript/graphics.html">
	                <span class="en">Graphics</span>
	              </a>
	          </li>
	          <li><a href="../../../guide/topics/renderscript/compute.html">
	                <span class="en">Compute</span>
	              </a>
	          </li>
	        </ul>
  	  </li>

      <li class="toggle-list">
          <div><a href="../../../guide/topics/media/index.html">
            <span class="en">Multimedia and Camera</span>
          </a><span class="new">updated</span></div>
          <ul>
            <li><a href="../../../guide/topics/media/mediaplayer.html">
                  <span class="en">Media Playback</span></a>
                </li>
            <li><a href="../../../guide/topics/media/jetplayer.html">
                  <span class="en">JetPlayer</span></a>
                </li>
            <li><a href="../../../guide/topics/media/camera.html">
                  <span class="en">Camera</span></a>
                  <span class="new">new!</span>
                </li>
            <li><a href="../../../guide/topics/media/audio-capture.html">
                  <span class="en">Audio Capture</span></a>
                </li>
          </ul>
      </li>
      <li>
        <a href="../../../guide/topics/clipboard/copy-paste.html">
            <span class="en">Copy and Paste</span>
        </a></li>
  <!--<li class="toggle-list">
        <div><a style="color:gray;">Sensors</a></div>
          <ul>
            <li><a style="color:gray;">Camera</a></li>
            <li><a style="color:gray;">Compass</a></li>
            <li><a style="color:gray;">Accelerometer</a></li>
          </ul>
      </li> -->
      <li class="toggle-list">
        <div><a href="../../../guide/topics/location/index.html">
               <span class="en">Location and Maps</span>
             </a></div>
        <ul>
          <li><a href="../../../guide/topics/location/obtaining-user-location.html">
                <span class="en">Obtaining User Location</span>
              </a></li>
        </ul>
      </li>
  <!--<li class="toggle-list">
        <div><a style="color:gray;">Wireless Controls</a></div>
          <ul>
            <li><a style="color:gray;">Wi-Fi</a></li>
          </ul>
      </li> -->
  <!--<li><a style="color:gray;">Localization</a></li>  -->
      <li><a href="../../../guide/topics/appwidgets/index.html">
            <span class="en">App Widgets</span></a>
          </li>
      <li><a href="../../../guide/topics/wireless/bluetooth.html">
            <span class="en">Bluetooth</span></a>
          </li>
      <li><a href="../../../guide/topics/nfc/index.html">
            <span class="en">Near Field Communication</span>
          </a></li>
      <li class="toggle-list">
          <div><a href="../../../guide/topics/usb/index.html">
            <span class="en">USB</span></a>
          </div>
            <ul>
              <li><a href="../../../guide/topics/usb/accessory.html">Accessory</a></li>
              <li><a href="../../../guide/topics/usb/host.html">Host</a></li>
              <li><a href="../../../guide/topics/usb/adk.html">Open Accessory Dev Kit</a></li>
            </ul>
          </li>

       <li><a href="../../../guide/topics/network/sip.html">
            <span class="en">Session Initiation Protocol</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/search/index.html">
            <span class="en">Search</span>
          </a></div>
          <ul>
            <li><a href="../../../guide/topics/search/search-dialog.html">Creating a Search Interface</a></li>
            <li><a href="../../../guide/topics/search/adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li>
            <li><a href="../../../guide/topics/search/adding-custom-suggestions.html">Adding Custom Suggestions</a></li>
            <li><a href="../../../guide/topics/search/searchable-config.html">Searchable Configuration</a></li>
          </ul>
      </li>
      <li><a href="../../../guide/topics/admin/device-admin.html">
            <span class="en">Device Administration</span></a>
      </li>
      <li class="toggle-list">
           <div>
                <a href="../../../guide/topics/testing/index.html">
                   <span class="en">Testing</span>
               </a>
           </div>
           <ul>
              <li>
                <a href="../../../guide/topics/testing/testing_android.html">
                <span class="en">Testing Fundamentals</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/activity_testing.html">
                <span class="en">Activity Testing</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/contentprovider_testing.html">
                <span class="en">Content Provider Testing</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/service_testing.html">
                <span class="en">Service Testing</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/what_to_test.html">
                <span class="en">What To Test</span></a>
              </li>
           </ul>
      </li>
    </ul>
  </li>

  <li>
    <h2>
      <span class="en">Android Market Topics</span>
    </h2>
    <ul>
      <li><a href="../../../guide/publishing/licensing.html">
          <span class="en">Application Licensing</span></a>
      </li>
      <li class="toggle-list">
        <div><a href="../../../guide/market/billing/index.html">
            <span class="en">In-app Billing</span></a>
        </div>
        <ul>
          <li><a href="../../../guide/market/billing/billing_overview.html">
              <span class="en">In-app Billing Overview</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_integrate.html">
              <span class="en">Implementing In-app Billing</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_best_practices.html">
              <span class="en">Security and Design</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_testing.html">
              <span class="en">Testing In-app Billing</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_admin.html">
              <span class="en">Administering In-app Billing</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_reference.html">
              <span class="en">In-app Billing Reference</span></a>
          </li>
        </ul>
      </li>
      <li><a href="../../../guide/appendix/market-filters.html">
          <span class="en">Market Filters</span></a>
      </li>
      <li><a href="../../../guide/market/publishing/multiple-apks.html">
          <span class="en">Multiple APK Support</span></a>
      </li>
    </ul>
  </li>


  <li>
    <h2><span class="en">Developing</span>
               <span class="de" style="display:none">Entwicklung</span>
               <span class="es" style="display:none">Desarrollo</span>
               <span class="fr" style="display:none">Développement</span>
               <span class="it" style="display:none">Sviluppo</span>
               <span class="ja" style="display:none">開発</span>
               <span class="zh-CN" style="display:none">开发</span>
               <span class="zh-TW" style="display:none">開發</span>
    </h2>
    <ul>
  <!--<li><a href="">Developing for Android</a></li>
      signing, upgrading, selecting a package name, select device profile, touch, trackball, dpad available, etc. -->
      <li>
        <a href="../../../guide/developing/index.html">
        <span class="en">Introduction</span></a>
      </li>

      <li class="toggle-list">
        <div>
           <a href="../../../guide/developing/devices/index.html">
                <span class="en">Managing Virtual Devices</span>
            </a>
        </div>
        <ul>
          <li>
            <a href="../../../guide/developing/devices/managing-avds.html">
              <span class="en">With AVD Manager</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/devices/managing-avds-cmdline.html">
              <span class="en">From the Command Line</span>
            </a>
          </li>
          <li>
           <a href="../../../guide/developing/devices/emulator.html">
                <span class="en">Using the Android Emulator</span>
            </a>
          </li>
        </ul>
      </li>
      <li>
        <a href="../../../guide/developing/device.html">
          <span class="en">Using Hardware Devices</span>
        </a>
      </li>

      <li class="toggle-list">
        <div>
          <a href="../../../guide/developing/projects/index.html">
            <span class="en">Managing Projects</span>
          </a>
        </div>
        <ul>
          <li>
            <a href="../../../guide/developing/projects/projects-eclipse.html">
              <span class="en">From Eclipse with ADT</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/projects/projects-cmdline.html">
                <span class="en">From the Command Line</span>
            </a>
          </li>
        </ul>
      </li>

      <li class="toggle-list">
        <div>
          <a href="../../../guide/developing/building/index.html">
            <span class="en">Building and Running</span>
          </a>
        </div>
        <ul>
          <li><a href="../../../guide/developing/building/building-eclipse.html">
            <span class="en">From Eclipse with ADT</span>
          </a></li>
          <li><a href="../../../guide/developing/building/building-cmdline.html">
            <span class="en">From the Command Line</span></a></li>
        </ul>
      </li>

      <li class="toggle-list">
        <div>
          <a href="../../../guide/developing/debugging/index.html">
            <span class="en">Debugging</span>
          </a>
        </div>
        <ul>
          <li>
            <a href="../../../guide/developing/debugging/debugging-projects.html">
                <span class="en">From Eclipse with ADT</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-projects-cmdline.html">
                <span class="en">From Other IDEs</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/ddms.html">
              <span class="en">Using DDMS</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-log.html">
                <span class="en">Reading and Writing Logs</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-ui.html">
                <span class="en">Debugging and Profiling UIs</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-tracing.html">
                <span class="en">Profiling with Traceview and dmtracedump</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-devtools.html">
                <span class="en">Using the Dev Tools App</span>
            </a>
          </li>
        </ul>
      </li>

      <li class="toggle-list">
           <div>
                <a href="../../../guide/developing/testing/index.html">
                   <span class="en">Testing</span>
               </a>
           </div>
           <ul>
              <li>
                <a href="../../../guide/developing/testing/testing_eclipse.html">
                  <span class="en">From Eclipse with ADT</span>
                </a>
              </li>

              <li>
                <a href="../../../guide/developing/testing/testing_otheride.html">
                  <span class="en">From Other IDEs</span>
                </a>
              </li>
           </ul>
         </li>

         <li class="toggle-list">
        <div><a href="../../../guide/developing/tools/index.html">
            <span class="en">Tools</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/developing/tools/adb.html">adb</a></li>
          <li><a href="../../../guide/developing/tools/adt.html">ADT</a></li>
          <li><a href="../../../guide/developing/tools/android.html">android</a></li>
          <li><a href="../../../guide/developing/tools/bmgr.html">bmgr</a>
          <li><a href="../../../guide/developing/tools/dmtracedump.html">dmtracedump</a></li>
          <li><a href="../../../guide/developing/tools/draw9patch.html">Draw
          9-Patch</a></li>
          <li><a href="../../../guide/developing/tools/emulator.html">Emulator</a></li>
          <li><a href="../../../guide/developing/tools/etc1tool.html">etc1tool</a></li>
          <li><a href="../../../guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a></li>
          <li><a href="../../../guide/developing/tools/hprof-conv.html">hprof-conv</a></li>
          <li><a href="../../../guide/developing/tools/layoutopt.html">layoutopt</a></li>
          <li><a href="../../../guide/developing/tools/logcat.html">logcat</a></li>
          <li><a href="../../../guide/developing/tools/mksdcard.html">mksdcard</a></li>
          <li><a href="../../../guide/developing/tools/monkey.html">Monkey</a></li>
          <li class="toggle-list">
            <div><a href="../../../guide/developing/tools/monkeyrunner_concepts.html">
              <span class="en">monkeyrunner</span>
            </a></div>
            <ul>
              <li><a href="../../../guide/developing/tools/MonkeyDevice.html">
                <span class="en">MonkeyDevice</span>
                </a></li>
              <li><a href="../../../guide/developing/tools/MonkeyImage.html">
                <span class="en">MonkeyImage</span>
                </a></li>
              <li><a href="../../../guide/developing/tools/MonkeyRunner.html">
                <span class="en">MonkeyRunner</span>
                </a></li>
            </ul>
          </li>
          <li><a href="../../../guide/developing/tools/proguard.html">ProGuard</a></li>
          <li><a href="../../../guide/developing/tools/adb.html#sqlite">sqlite3</a></li>
          <li><a href="../../../guide/developing/tools/traceview.html">Traceview</a></li>
          <li><a href="../../../guide/developing/tools/zipalign.html">zipalign</a></li>
        </ul>
      </li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Publishing</span>
        <span class="de" style="display:none">Veröffentlichung</span>
        <span class="es" style="display:none">Publicación</span>
        <span class="fr" style="display:none">Publication</span>
        <span class="it" style="display:none">Pubblicazione</span>
        <span class="ja" style="display:none">公開</span>
        <span class="zh-CN" style="display:none">发布</span>
        <span class="zh-TW" style="display:none">發佈</span>
    </h2>
    <ul>
      <li><a href="../../../guide/publishing/app-signing.html">
            <span class="en">Signing Your Applications</span>
            <span class="de" style="display:none">Signieren Ihrer Anwendungen</span>
            <span class="es" style="display:none">Firma de aplicaciones</span>
            <span class="fr" style="display:none">Attribution de votre signature <br />à vos applications</span>
            <span class="it" style="display:none">Firma delle applicazioni</span>
            <span class="ja" style="display:none">アプリケーションへの署名</span>
            <span class="zh-CN" style="display:none">应用程序签名</span>
            <span class="zh-TW" style="display:none">簽署應用程式</span>
          </a></li>
      <li><a href="../../../guide/publishing/versioning.html">
            <span class="en">Versioning Your Applications</span>
            <span class="de" style="display:none">Versionsverwaltung für Ihre <br />Anwendungen</span>
            <span class="es" style="display:none">Versiones de las aplicaciones</span>
            <span class="fr" style="display:none">Attribution d'une version à vos applications</span>
            <span class="it" style="display:none">Controllo versioni delle applicazioni</span>
            <span class="ja" style="display:none">アプリケーションのバージョニング</span>
            <span class="zh-CN" style="display:none">应用程序版本控制</span>
            <span class="zh-TW" style="display:none">應用程式版本設定</span>
          </a></li>
      <li><a href="../../../guide/publishing/preparing.html">
            <span class="en">Preparing to Publish</span>
            <span class="de" style="display:none">Vorbereitung auf die Veröffentlichung</span>
            <span class="es" style="display:none">Publicación de aplicaciones</span>
            <span class="fr" style="display:none">Préparation à la publication</span>
            <span class="it" style="display:none">Preparativi per la pubblicazione</span>
            <span class="ja" style="display:none">公開の準備</span>
            <span class="zh-CN" style="display:none">准备发布</span>
            <span class="zh-TW" style="display:none">準備發佈</span>
          </a></li>
      <li><a href="../../../guide/publishing/publishing.html">
            <span class="en">Publishing on Android Market</span>
          </a></li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Best Practices</span>
               <span class="de" style="display:none">Bewährte Verfahren</span>
               <span class="es" style="display:none">Prácticas recomendadas</span>
               <span class="fr" style="display:none">Meilleures pratiques</span>
               <span class="it" style="display:none">Best practice</span>
               <span class="ja" style="display:none">ベスト プラクティス</span>
               <span class="zh-CN" style="display:none">最佳实践</span>
               <span class="zh-TW" style="display:none">最佳實務</span>
    </h2>
    <ul>
      <li><a href="../../../guide/practices/compatibility.html">
            <span class="en">Compatibility</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/practices/screens_support.html">
          <span class="en">Supporting Multiple Screens</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/practices/screens-distribution.html">
            <span class="en">Distributing to Specific Screens</span>
          </a></li>
          <li><a href="../../../guide/practices/screen-compat-mode.html">
            <span class="en">Screen Compatibility Mode</span>
          </a></li>
          <li><a href="../../../guide/practices/screens-support-1.5.html">
            <span class="en">Strategies for Android 1.5</span>
          </a></li>
        </ul>
      </li>
      <li><a href="../../../guide/practices/optimizing-for-3.0.html">
            <span class="en">Optimizing Apps for Android 3.0</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/practices/ui_guidelines/index.html">
               <span class="en">UI Guidelines</span>
             </a></div>
        <ul>
          <li class="toggle-list">
            <div><a href="../../../guide/practices/ui_guidelines/icon_design.html">
                   <span class="en">Icon Design <span class="new">updated</span></span>
                 </a></div>
            <ul>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_launcher.html">
                    <span class="en">Launcher Icons <span class="new">updated</span></span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_menu.html">
                    <span class="en">Menu Icons</span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_action_bar.html">
                    <span class="en">Action Bar Icons <span class="new">new!</span></span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_status_bar.html">
                    <span class="en">Status Bar Icons <span class="new">updated</span></span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_tab.html">
                    <span class="en">Tab Icons</span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_dialog.html">
                    <span class="en">Dialog Icons</span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_list.html">
                    <span class="en">List View Icons</span>
                  </a></li>
            </ul>
          </li>
          <li><a href="../../../guide/practices/ui_guidelines/widget_design.html">
                <span class="en">App Widget Design <span class="new">updated</span></span>
              </a></li>
          <li><a href="../../../guide/practices/ui_guidelines/activity_task_design.html">
                <span class="en">Activity and Task Design</span>
              </a></li>
          <li><a href="../../../guide/practices/ui_guidelines/menu_design.html">
                <span class="en">Menu Design</span>
              </a></li>
        </ul>
      </li>
      </ul>
      <ul>
      <li><a href="../../../guide/practices/design/accessibility.html">
            <span class="en">Designing for Accessibility</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/practices/design/performance.html">
            <span class="en">Designing for Performance</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/practices/design/jni.html">
                <span class="en">JNI Tips</span>
              </a></li>
        </ul>
      </li>
      <li><a href="../../../guide/practices/design/responsiveness.html">
            <span class="en">Designing for Responsiveness</span>
          </a></li>
      <li><a href="../../../guide/practices/design/seamlessness.html">
            <span class="en">Designing for Seamlessness</span>
          </a></li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Web Applications</span>
    </h2>
    <ul>
      <li><a href="../../../guide/webapps/index.html">
            <span class="en">Web Apps Overview</span>
          </a></li>
      <li><a href="../../../guide/webapps/targeting.html">
            <span class="en">Targeting Screens from Web Apps</span>
          </a></li>
      <li><a href="../../../guide/webapps/webview.html">
            <span class="en">Building Web Apps in WebView</span>
          </a></li>
      <li><a href="../../../guide/webapps/debugging.html">
            <span class="en">Debugging Web Apps</span>
          </a></li>
      <li><a href="../../../guide/webapps/best-practices.html">
            <span class="en">Best Practices for Web Apps</span>
          </a></li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Appendix</span>
               <span class="de" style="display:none">Anhang</span>
               <span class="es" style="display:none">Apéndice</span>
               <span class="fr" style="display:none">Annexes</span>
               <span class="it" style="display:none">Appendice</span>
               <span class="ja" style="display:none">付録</span>
               <span class="zh-CN" style="display:none">附录</span>
               <span class="zh-TW" style="display:none">附錄</span>
    </h2>
    <ul>
      <li><a href="../../../guide/appendix/api-levels.html">
            <span class="en">Android API Levels</span>
          </a></li>
      <li><a href="../../../guide/appendix/install-location.html">
            <span class="en">App Install Location</span>
          </a></li>
      <li><a href="../../../guide/appendix/media-formats.html">
            <span class="en">Supported Media Formats <span class="new">updated</span></span>
          </a></li>
      <li><a href="../../../guide/appendix/g-app-intents.html">
            <span class="en">Intents List: Google Apps</span>
          </a></li>
      <li><a href="../../../guide/developing/tools/aidl.html">AIDL</a></li>
      <li><a href="../../../guide/appendix/glossary.html">
            <span class="en">Glossary</span>
          </a></li>
    </ul>
  </li>

</ul>

<script type="text/javascript">
<!--
    buildToggleLists();
    changeNavLang(getLangPref());
//-->
</script>

      </div>
    </div> <!-- end side-nav -->
    <script>
      addLoadEvent(function() {
        scrollIntoView("devdoc-nav");
        });
    </script>




<div class="g-unit" id="doc-content"><a name="top"></a>

<div id="jd-header" class="guide-header">
  <span class="crumb">
    &nbsp;
    
  </span>
<h1>App Widgets</h1>
</div>

  <div id="jd-content">

    <div class="jd-descr">
    <div id="qv-wrapper">
  <div id="qv">
    <h2>Quickview</h2>
    <ul>
      <li>App Widgets provide users access to some of your application features
directly from the Home screen (without the need to launch an activity)</li>
      <li>App Widgets are backed by a special kind of broadcast receiver that
handles the App
Widget lifecycle</li>
    </ul>
    
    <h2>In this document</h2>
    <ol>
      <li><a href="#Basics">The Basics</a></li>
      <li><a href="#Manifest">Declaring an App Widget in the Manifest</a></li>
      <li><a href="#MetaData">Adding the AppWidgetProviderInfo Metadata</a></li>
      <li><a href="#CreatingLayout">Creating the App Widget Layout</a></li>
      <li><a href="#AppWidgetProvider">Using the AppWidgetProvider Class</a>
        <ol>
          <li><a href="#ProviderBroadcasts">Receiving App Widget broadcast
Intents</a></li>
        </ol>
      </li>
      <li><a href="#Configuring">Creating an App Widget Configuration
Activity</a>
        <ol>
          <li><a href="#UpdatingFromTheConfiguration">Updating the App Widget
from 
            the configuration Activity</a></li>
        </ol>
      </li>
      <li><a href="#preview">Setting a Preview Image</a></li>
      <li><a href="#collections">Using App Widgets with Collections</a>
        <ol>
          <li><a href="#collection_sample">Sample application</a></li>
          <li><a href="#implementing_collections">Implementing app widgets with
collections
</a></li>
          <li><a href="#fresh">Keeping Collection Data Fresh</a></li>
        </ol>   
      </li>
    </ol>

    <h2>Key classes</h2>
    <ol>
      <li><code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code></li>
      <li><code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html">AppWidgetProviderInfo</a></code></li>
      <li><code><a href="../../../reference/android/appwidget/AppWidgetManager.html">AppWidgetManager</a></code></li>
    </ol>
    
    <h2>See also</h2>
    <ol>
      <li><a
href="../../../guide/practices/ui_guidelines/widget_design.html">App Widget
Design 
        Guidelines</a></li>
      <li><a
href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-
widgets-and.html">Introducing
        home screen widgets and the AppWidget framework &raquo;</a></li>
    </ol>
  </div>
</div>


<p>App Widgets are miniature application views that can be embedded in other
applications
(such as the Home screen) and receive periodic updates. These views are
referred 
to as Widgets in the user interface,
and you can publish one with an App Widget provider. An application component
that is 
able to hold other App Widgets is called an App Widget host. The screenshot
below shows
the Music App Widget.</p>

<img src="../../../images/appwidget.png" alt="" />

<p>This document describes how to publish an App Widget using an App Widget
provider.</p>


<h2 id="Basics">The Basics</h2>

<p>To create an App Widget, you need the following:</p>

<dl>
  <dt><code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html">AppWidgetProviderInfo</a></code> object</dt>
  <dd>Describes the metadata for an App Widget, such as the App Widget's layout,
update frequency,
    and the AppWidgetProvider class. This should be defined in XML.</dd>
  <dt><code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> class implementation</dt>
  <dd>Defines the basic methods that allow you to programmatically interface
with the App Widget,
    based on broadcast events. Through it, you will receive broadcasts when the
App Widget is updated, 
    enabled, disabled and deleted.</dd>
  <dt>View layout</dt>
  <dd>Defines the initial layout for the App Widget, defined in XML.</dd>
</dl>

<p>Additionally, you can implement an App Widget configuration Activity. This is
an optional 
<code><a href="../../../reference/android/app/Activity.html">Activity</a></code> that launches when the user adds your App Widget
and allows him or her
to modify App Widget settings at create-time.</p>

<p>The following sections describe how to setup each of these components.</p>


<h2 id="Manifest">Declaring an App Widget in the Manifest</h2>

<p>First, declare the <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> class in your
application's
<code>AndroidManifest.xml</code> file. For example:</p>

<pre>
&lt;receiver android:name="ExampleAppWidgetProvider" >
    &lt;intent-filter>
        &lt;action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    &lt;/intent-filter>
    &lt;meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
&lt;/receiver>
</pre>

<p>The <code>&lt;receiver&gt;</code> element requires the
<code>android:name</code> 
attribute, which specifies the <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> used
by the App Widget.</p>

<p>The <code>&lt;intent-filter&gt;</code> element must include an
<code>&lt;action></code>
element with the <code>android:name</code> attribute. This attribute specifies
that the <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> accepts the <code><a href="../../../reference/android/appwidget/AppWidgetManager.html#ACTION_APPWIDGET_UPDATE">ACTION_APPWIDGET_UPDATE</a></code> broadcast.
This is the only broadcast that you must explicitly declare. The <code><a href="../../../reference/android/appwidget/AppWidgetManager.html">AppWidgetManager</a></code>
automatically sends all other App Widget broadcasts to the AppWidgetProvider as
necessary.</p>

<p>The <code>&lt;meta-data&gt;</code> element specifies the
<code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html">AppWidgetProviderInfo</a></code> resource and requires the 
following attributes:</p>
<ul>
  <li><code>android:name</code> - Specifies the metadata name. Use
<code>android.appwidget.provider</code>
    to identify the data as the <code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html">AppWidgetProviderInfo</a></code>
descriptor.</li>
  <li><code>android:resource</code> - Specifies the <code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html">AppWidgetProviderInfo</a></code> 
    resource location.</li>
</ul>


<h2 id="MetaData">Adding the AppWidgetProviderInfo Metadata</h2>

<p>The <code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html">AppWidgetProviderInfo</a></code> defines the essential 
qualities of an App Widget, such as its minimum layout dimensions, its initial
layout resource,
how often to update the App Widget, and (optionally) a configuration Activity to
launch at create-time.
Define the AppWidgetProviderInfo object in an XML resource using a single
<code>&lt;appwidget-provider></code> element and save it in the project's
<code>res/xml/</code> 
folder.</p>

<p>For example:</p>

<pre>
&lt;appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="294dp"
    android:minHeight="72dp"
    android:updatePeriodMillis="86400000"
    android:previewImage="@drawable/preview"
    android:initialLayout="@layout/example_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigure" 
    android:resizeMode="horizontal|vertical">
&lt;/appwidget-provider>
</pre>

<p>Here's a summary of the <code>&lt;appwidget-provider></code> attributes:</p>
<ul>
  <li>The values for the <code>minWidth</code> and <code>minHeight</code>
attributes specify the minimum
    area required by the App Widget's layout. 
    <p>The default Home screen positions App Widgets in its window based on a
grid of
    cells that have a defined height and width. If the values for an App
Widget's minimum width 
    or height don't match the dimensions of the cells,
    then the App Widget dimensions round <em>up</em> to the nearest cell size.
    (See the <a
href="../../../guide/practices/ui_guidelines/widget_design.html">App Widget
Design 
    Guidelines</a> for more information on the Home screen cell sizes.)</p>
    <p>Because the Home screen's layout orientation (and thus, the cell sizes)
can change,
    as a rule of thumb, you should assume the worst-case cell size of 74 pixels
for the height
    <em>and</em> width of a cell. However, you must subtract 2 from the final
dimension to account
    for any integer rounding errors that occur in the pixel count. To find your
minimum width
    and height in density-independent pixels (dp), use this formula:<br/>
      <code>(number of cells * 74) - 2</code><br/>
    Following this formula, you should use 72 dp for a height of one cell, 294
dp and for a width of four cells.</p>
<p class="note"><strong>Note:</strong> To make your app widget portable across
devices, your app widget's minimum size should never be larger than 4 x 4 cells.
See the <a
href="../../../guide/practices/ui_guidelines/widget_design.html#sizes">App
Widget Design Guidelines</a> for more discussion of Home screen cell sizes.</p>
  </li>
  <li>The <code>updatePeriodMillis</code> attribute defines how often the App
Widget framework should request an update from the <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> by calling the 
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
callback method. The actual update
is not guaranteed to occur exactly on time with this value and we suggest
updating as infrequently as possible&mdash;perhaps no more than once an hour to
conserve the battery. You might also allow the user to adjust the frequency in a
configuration&mdash;some people might want a stock ticker to update every 15
minutes, or maybe only four times a day. 
    	<p class="note"><strong>Note:</strong> If the device is asleep when it
is time for an update 
    	(as defined by <code>updatePeriodMillis</code>), then the device will
wake up in order 
    	to perform the update. If you don't update more than once per hour, this
probably won't 
    	cause significant problems for the battery life. If, however, you need
to update more 
    	frequently and/or you do not need to update while the device is asleep,
then you can instead 
    	perform updates based on an alarm that will not wake the device. To do
so, set an alarm with 
    	an Intent that your AppWidgetProvider receives, using the	<code><a href="../../../reference/android/app/AlarmManager.html">AlarmManager</a></code>. 
    	Set the alarm type to either <code><a href="../../../reference/android/app/AlarmManager.html#ELAPSED_REALTIME">ELAPSED_REALTIME</a></code> or 
    	<code><a href="../../../reference/android/app/AlarmManager.html#RTC">RTC</a></code>, which will only
    	deliver the alarm when the device is awake. Then set
<code>updatePeriodMillis</code> to 
    	zero (<code>"0"</code>).</p>
  </li>
  <li>The <code>initialLayout</code> attribute points to the layout resource
that defines the
    App Widget layout.</li>
  <li>The <code>configure</code> attribute defines the <code><a href="../../../reference/android/app/Activity.html">Activity</a></code> to launch when
    the user adds the App Widget, in order for him or her to configure App
Widget properties. This is optional
    (read <a href="#Configuring">Creating an App Widget Configuration
Activity</a> below).</li>
    
   <li>The <code>previewImage</code> attribute specifies a preview of what the
app widget will look like after it's configured, which the user sees when
selecting the app widget. If not supplied, the user instead sees your
application's launcher icon. This field corresponds to the
<code>android:previewImage</code> attribute in the <code>&lt;receiver&gt;</code>
element in the <code>AndroidManifest.xml</code> file. For more discussion of
using <code>previewImage</code>, see <a href="#preview">Setting a Preview
Image</a>. Introduced in Android 3.0.</li>

   <li>The <code>autoAdvanceViewId</code> attribute specifies the view ID of the
app widget subview that should be auto-advanced by the widget's host. Introduced in Android 3.0.</li> 

<li>The <code>resizeMode</code> attribute specifies the rules by which a widget
can be resized. You use this attribute to make homescreen widgets
resizeable&mdash;horizontally, vertically, or on both axes. Users touch-hold a
widget to show its resize handles, then drag the horizontal and/or vertical
handles to change the size on the layout grid. Values for the
<code>resizeMode</code> attribute include "horizontal", "vertical", and "none".
To declare a widget as resizeable horizontally and vertically, supply the value
"horizontal|vertical". Introduced in Android 3.1.</li> </ul>

<p>See the <code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html">AppWidgetProviderInfo</a></code> class for more
information on the
attributes accepted by the <code>&lt;appwidget-provider></code> element.</p>


<h2 id="CreatingLayout">Creating the App Widget Layout</h2>

<p>You must define an initial layout for your App Widget in XML and save it in
the project's
<code>res/layout/</code> directory. You can design your App Widget using the
View objects listed
below, but before you begin designing your App Widget, please read and
understand the
<a href="../../../guide/practices/ui_guidelines/widget_design.html">App Widget
Design 
Guidelines</a>.</p>

<p>Creating the App Widget layout is simple if you're
familiar with <a
href="../../../guide/topics/ui/declaring-layout.html">XML Layouts</a>.
However, you must be aware that App Widget layouts are based on <code><a href="../../../reference/android/widget/RemoteViews.html">RemoteViews</a></code>,
which do not support every kind of layout or view widget.</p>

<p>A RemoteViews object (and, consequently, an App Widget) can support the 
following layout classes:</p>

<ul class="nolist">
  <li><code><a href="../../../reference/android/widget/FrameLayout.html">FrameLayout</a></code></li>
  <li><code><a href="../../../reference/android/widget/LinearLayout.html">LinearLayout</a></code></li>
  <li><code><a href="../../../reference/android/widget/RelativeLayout.html">RelativeLayout</a></code></li>
</ul>

<p>And the following widget classes:</p>
<ul class="nolist">
  <li><code><a href="../../../reference/android/widget/AnalogClock.html">AnalogClock</a></code></li>
  <li><code><a href="../../../reference/android/widget/Button.html">Button</a></code></li>
  <li><code><a href="../../../reference/android/widget/Chronometer.html">Chronometer</a></code></li>
  <li><code><a href="../../../reference/android/widget/ImageButton.html">ImageButton</a></code></li>
  <li><code><a href="../../../reference/android/widget/ImageView.html">ImageView</a></code></li>
  <li><code><a href="../../../reference/android/widget/ProgressBar.html">ProgressBar</a></code></li>
  <li><code><a href="../../../reference/android/widget/TextView.html">TextView</a></code></li>
  <li><code><a href="../../../reference/android/widget/ViewFlipper.html">ViewFlipper</a></code></li>
</ul>

<p>Descendants of these classes are not supported.</p>


<h3 id="AddingMargins">Adding margins to App Widgets</h3>

<p>Widgets should not generally extend to screen edges and should not visually be flush with other widgets, so you should add margins on all sides around your widget frame.</p>

<p>As of Android 4.0, app widgets are automatically given padding between the widget frame and the app widget's bounding box to provide better alignment with other widgets and icons on the user's home screen. To take advantage of this strongly recommended behavior, set your application's <a href="../../../guide/topics/manifest/uses-sdk-element.html">targetSdkVersion</a> to 14 or greater.</p>

<p>It's easy to write a single layout that has custom margins applied for earlier versions of the platform, and has no extra margins for Android 4.0 and greater:</p>

<ol>
  <li>Set your application's <code>targetSdkVersion</code> to 14 or greater.</li>
  <li>Create a layout such as the one below, that references a <a href="../../../guide/topics/resources/more-resources.html#Dimension">dimension resource</a> for its margins:

<pre>
&lt;FrameLayout
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  <strong>android:layout_margin="@dimen/widget_margin"&gt;</strong>

  &lt;LinearLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="horizontal"
    android:background="@drawable/my_widget_background"&gt;
    &hellip;
  &lt;/LinearLayout&gt;

&lt;/FrameLayout&gt;
</pre>

  </li>
  <li>Create two dimensions resources, one in <code>res/values/</code> to provide the pre-Android 4.0 custom margins, and one in <code>res/values-v14/</code> to provide no extra padding for Android 4.0 widgets:

    <p><strong>res/values/dimens.xml</strong>:<br>
    <pre>&lt;dimen name="widget_margin"&gt;15dp&lt;/dimen&gt;</pre></p>

    <p><strong>res/values-v14/dimens.xml</strong>:<br>
    <pre>&lt;dimen name="widget_margin"&gt;0dp&lt;/dimen&gt;</pre></p>
  </li>
</ol>

<p>Another option is to simply build extra margins into your <a href="../../../guide/topics/graphics/2d-graphics.html#nine-patch">nine-patch</a> background assets by default, and provide different nine-patches with no margins for API level 14 or later.</p>


<h2 id="AppWidgetProvider">Using the AppWidgetProvider Class</h2>

<div class="sidebox-wrapper">
<div class="sidebox">
    <p>You must declare your AppWidgetProvider class implementation as a
broadcast receiver 
    using the <code>&lt;receiver></code> element in the AndroidManifest (see
    <a href="#Manifest">Declaring an App Widget in the Manifest</a> above).</p>
  </div>
</div>

<p>The <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> class extends
BroadcastReceiver as a convenience
class to handle the App Widget broadcasts. The AppWidgetProvider receives only
the event broadcasts that
are relevant to the App Widget, such as when the App Widget is updated, deleted,
enabled, and disabled.
When these broadcast events occur, the AppWidgetProvider receives the following
method calls:</p>

<dl>
  <dt>
  <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
</dt>
    <dd>This is called to update the App Widget at intervals defined by the
<code>updatePeriodMillis</code>
    attribute in the AppWidgetProviderInfo (see <a href="#MetaData">Adding the 
    AppWidgetProviderInfo Metadata</a> above). This method is also called
    when the user adds the App Widget, so it should perform the essential setup,
    such as define event handlers for Views and start a temporary
    <code><a href="../../../reference/android/app/Service.html">Service</a></code>, if necessary. However, if you have declared a
configuration
    Activity, <strong>this method is not called</strong> when the user adds the
App Widget,
    but is called for the subsequent updates. It is the responsibility of the 
    configuration Activity to perform the first update when configuration is
done.
    (See <a href="#Configuring">Creating an App Widget Configuration
Activity</a> below.)</dd> 
  <dt><code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onDeleted(android.content.Context, int[])">onDeleted(Context, int[])</a></code></dt>
    <dd>This is called every time an App Widget is deleted from the App Widget
host.</dd>
  <dt><code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onEnabled(android.content.Context)">onEnabled(Context)</a></code></dt>
    <dd>This is called when an instance the App Widget is created for the first
time. For example, if the user 
    adds two instances of your App Widget, this is only called the first time.
    If you need to open a new database or perform other setup that only needs to
occur once 
    for all App Widget instances, then this is a good place to do it.</dd> 
  <dt><code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onDisabled(android.content.Context)">onDisabled(Context)</a></code></dt>
    <dd>This is called when the last instance of your App Widget is deleted from
the App Widget host. 
    This is where you should clean up any work done in 
    <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onEnabled(android.content.Context)">onEnabled(Context)</a></code>, 
    such as delete a temporary database.</dd> 
  <dt><code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onReceive(android.content.Context, android.content.Intent)">onReceive(Context, Intent)</a></code></dt>
    <dd>This is called for every broadcast and before each of the above callback
methods.
    You normally don't need to implement this method because the default
AppWidgetProvider 
    implementation filters all App Widget broadcasts and calls the above 
    methods as appropriate.</dd> 
</dl>

<p class="warning"><strong>Note:</strong> In Android 1.5, there is a known issue
in which the
<code>onDeleted()</code> method will not be called when it should be. To work
around this issue, 
you can implement <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onReceive(android.content.Context, android.content.Intent)">onReceive()</a></code> as described in this 
<a
href="http://groups.google.com/group/android-developers/msg/e405ca19df2170e2">
Group post</a>
to receive the <code>onDeleted()</code> callback.
</p>

<p>The most important AppWidgetProvider callback is 
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
because it is called when
each App Widget is added to a host (unless you use a configuration Activity). If
your App Widget accepts any user interaction events, then you need to register
the event handlers in this callback. If your App Widget doesn't create temporary
files or databases, or perform other work that requires clean-up, then 
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
may be the only callback
method you need to define. For example, if you want an App Widget with a button
that launches an Activity when clicked, you could use the following
implementation of AppWidgetProvider:</p>

<pre>
public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        final int N = appWidgetIds.length;

        // Perform this loop procedure for each App Widget that belongs to this provider
        for (int i=0; i&lt;N; i++) {
            int appWidgetId = appWidgetIds[i];

            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, intent, 0);

            // Get the layout for the App Widget and attach an on-click listener
            // to the button
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.appwidget_provider_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app widget
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}
</pre>

<p>This AppWidgetProvider defines only the 
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
method for the purpose of
defining a <code><a href="../../../reference/android/app/PendingIntent.html">PendingIntent</a></code> that launches an <code><a href="../../../reference/android/app/Activity.html">Activity</a></code> and attaching it to the App Widget's button with <code><a href="../../../reference/android/widget/RemoteViews.html#setOnClickPendingIntent(int, android.app.PendingIntent)">setOnClickPendingIntent(int, PendingIntent)</a></code>. Notice
that it includes a loop that iterates through each entry in
<code>appWidgetIds</code>, which is an array of IDs that identify each App
Widget created by this provider. In this way, if the user creates more than one
instance of the App Widget, then they are all updated simultaneously. However,
only one <code>updatePeriodMillis</code> schedule will be managed for all
instances of the App Widget. For example, if the update schedule is defined to
be every two hours, and a second instance of the App Widget is added one hour
after the first one, then they will both be updated on the period defined by the
first one and the second update period will be ignored (they'll both be updated
every two hours, not every hour).</p>

<p class="note"><strong>Note:</strong> Because <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> is an extension of <code><a href="../../../reference/android/content/BroadcastReceiver.html">BroadcastReceiver</a></code>, your process is not guaranteed to keep
running after the callback methods return (see <code><a href="../../../reference/android/content/BroadcastReceiver.html">BroadcastReceiver</a></code> for information about the broadcast
lifecycle). If your App Widget setup process can take several seconds (perhaps
while performing web requests) and you require that your process continues,
consider starting a <code><a href="../../../reference/android/app/Service.html">Service</a></code> in the 
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
method. From within the Service, you can perform your own updates
to the App Widget without worrying about the AppWidgetProvider closing down due
to an <a href="../../../guide/practices/design/responsiveness.html">Application
Not Responding</a> (ANR) error. See the <a
href="http://code.google.com/p/wiktionary-android/source/browse/trunk/Wiktionary
/src/com/example/android/wiktionary/WordWidget.java">Wiktionary sample's
AppWidgetProvider</a> for an example of an App Widget running a <code><a href="../../../reference/android/app/Service.html">Service</a></code>.</p>

<p>Also see the <a 
href="../../../resources/samples/ApiDemos/src/com/example/android/apis/
appwidget/ExampleAppWidgetProvider.html">
ExampleAppWidgetProvider.java</a> sample class.</p>


<h3 id="ProviderBroadcasts">Receiving App Widget broadcast Intents</h3>

<p><code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> is just a convenience class.  If
you would like
to receive the App Widget broadcasts directly, you can implement your own 
<code><a href="../../../reference/android/content/BroadcastReceiver.html">BroadcastReceiver</a></code> or override the 
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onReceive(android.content.Context, android.content.Intent)">onReceive(Context, Intent)</a></code> callback. 
The four Intents you need to care about are:</p>
<ul>
  <li><code><a href="../../../reference/android/appwidget/AppWidgetManager.html#ACTION_APPWIDGET_UPDATE">ACTION_APPWIDGET_UPDATE</a></code></li>
  <li><code><a href="../../../reference/android/appwidget/AppWidgetManager.html#ACTION_APPWIDGET_DELETED">ACTION_APPWIDGET_DELETED</a></code></li>
  <li><code><a href="../../../reference/android/appwidget/AppWidgetManager.html#ACTION_APPWIDGET_ENABLED">ACTION_APPWIDGET_ENABLED</a></code></li>
  <li><code><a href="../../../reference/android/appwidget/AppWidgetManager.html#ACTION_APPWIDGET_DISABLED">ACTION_APPWIDGET_DISABLED</a></code></li>
</ul>



<h2 id="Configuring">Creating an App Widget Configuration Activity</h2>

<p>If you would like the user to configure settings when he or she adds a new
App Widget,
you can create an App Widget configuration Activity. This <code><a href="../../../reference/android/app/Activity.html">Activity</a></code> 
will be automatically launched by the App Widget host and allows the user to
configure
available settings for the App Widget at create-time, such as the App Widget
color, size, 
update period or other functionality settings.</p>

<p>The configuration Activity should be declared as a normal Activity in the
Android manifest file.
However, it will be launched by the App Widget host with the <code><a href="../../../reference/android/appwidget/AppWidgetManager.html#ACTION_APPWIDGET_CONFIGURE">ACTION_APPWIDGET_CONFIGURE</a></code> action,
so the Activity needs to accept this Intent. For example:</p>

<pre>
&lt;activity android:name=".ExampleAppWidgetConfigure">
    &lt;intent-filter>
        &lt;action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    &lt;/intent-filter>
&lt;/activity>
</pre>

<p>Also, the Activity must be declared in the AppWidgetProviderInfo XML file,
with the 
<code>android:configure</code> attribute (see <a href="#MetaData">Adding 
the AppWidgetProviderInfo Metadata</a> above). For example, the configuration
Activity
can be declared like this:</p>

<pre>
&lt;appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigure" 
    ... >
&lt;/appwidget-provider>
</pre>

<p>Notice that the Activity is declared with a fully-qualified namespace,
because 
it will be referenced from outside your package scope.</p>

<p>That's all you need to get started with a configuration Activity. Now all you
need is the actual
Activity. There are, however, two important things to remember when you
implement the Activity:</p>
<ul>
  <li>The App Widget host calls the configuration Activity and the configuration
Activity should always 
    return a result. The result should include the App Widget ID
    passed by the Intent that launched the Activity (saved in the Intent extras
as
    <code><a href="../../../reference/android/appwidget/AppWidgetManager.html#EXTRA_APPWIDGET_ID">EXTRA_APPWIDGET_ID</a></code>).</li>
  <li>The 
  <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
    method <strong>will not be called</strong> when the App Widget
is created
    (the system will not send the ACTION_APPWIDGET_UPDATE broadcast when a
configuration Activity
    is launched). It is the responsibility of the configuration Activity to
request an update from the 
    AppWidgetManager when the App Widget is first created. However, 
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> 
    will be called for subsequent updates&mdash;it is only skipped
the first time.</li>
</ul>

<p>See the code snippets in the following section for an example of how to
return a result
from the configuration and update the App Widget.</p>


<h3 id="UpdatingFromTheConfiguration">Updating the App Widget from the
configuration Activity</h3>

<p>When an App Widget uses a configuration Activity, it is the responsibility of
the Activity
to update the App Widget when configuration is complete. 
You can do so by requesting an update directly from the 
<code><a href="../../../reference/android/appwidget/AppWidgetManager.html">AppWidgetManager</a></code>.</p>

<p>Here's a summary of the procedure to properly update the App Widget and close
the configuration Activity:</p>

<ol>
  <li>First, get the App Widget ID from the Intent that launched the Activity:
<pre>
Intent intent = getIntent();
Bundle extras = intent.getExtras();
if (extras != null) {
    mAppWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_APPWIDGET_ID, 
            AppWidgetManager.INVALID_APPWIDGET_ID);
}
</pre>
  </li>
  <li>Perform your App Widget configuration.</li>
  <li>When the configuration is complete, get an instance of the
AppWidgetManager by calling
    <code><a href="../../../reference/android/appwidget/AppWidgetManager.html#getInstance(android.content.Context)">getInstance(Context)</a></code>:
<pre>
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
</pre>
  </li>
  <li>Update the App Widget with a <code><a href="../../../reference/android/widget/RemoteViews.html">RemoteViews</a></code> layout by
calling
    <code><a href="../../../reference/android/appwidget/AppWidgetManager.html#updateAppWidget(int, android.widget.RemoteViews)">updateAppWidget(int, RemoteViews)</a></code>:
<pre>
RemoteViews views = new RemoteViews(context.getPackageName(),
R.layout.example_appwidget);
appWidgetManager.updateAppWidget(mAppWidgetId, views);
</pre>
  </li>
  <li>Finally, create the return Intent, set it with the Activity result, and
finish the Activity:</li>
<pre>
Intent resultValue = new Intent();
resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, mAppWidgetId);
setResult(RESULT_OK, resultValue);
finish();
</pre>
  </li>
</ol>

<p class="note"><strong>Tip:</strong> When your configuration Activity first
opens, set
the Activity result to RESULT_CANCELED. This way, if the user backs-out of the
Activity before
reaching the end, the App Widget host is notified that the configuration was
cancelled and the
App Widget will not be added.</p>

<p>See the <a 
href="../../../resources/samples/ApiDemos/src/com/example/android/apis/
appwidget/ExampleAppWidgetConfigure.html">
ExampleAppWidgetConfigure.java</a> sample class in ApiDemos for an example.</p>

<h2 id="preview">Setting a Preview Image</h2>

<p>Android 3.0 introduces the <code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html#previewImage">previewImage</a></code> field, which specifies a
preview of what the app widget looks like. This preview is shown to the user from the
widget picker. If this field is not supplied, the app widget's icon is used for
the preview.</p> 

<p>This is how you specify this setting in XML:</p>

<pre>&lt;appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:previewImage="@drawable/preview">
&lt;/appwidget-provider></pre>

<p>To help create a preview image for your app widget (to specify in the <code><a href="../../../reference/android/appwidget/AppWidgetProviderInfo.html#previewImage">previewImage</a></code> field), the Android
emulator includes an application called &quot;Widget Preview.&quot; To create a
preview image, launch this application, select the app widget for your
application and set it up how you'd like your preview image to appear, then save
it and place it in your application's drawable resources.</p>

<h2 id="collections">Using App Widgets with Collections</h2>

<p>Android 3.0 introduces App Widgets with collections. These kinds of App
Widgets use the <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> to display collections
that are backed by remote data, such as from a <a
href="../../../guide/topics/providers/content-providers.html">content
provider</a>. The data provided by the <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code>
is presented in the App Widget using one of the following view types, which
we’ll refer to as “collection views:”</p>

<dl>
  <dt><code><a href="../../../reference/android/widget/ListView.html">ListView</a></code></dt>
  <dd>A view that shows items in a
vertically scrolling
list. For an example, see the Gmail app widget. </dd>
<dt><code><a href="../../../reference/android/widget/GridView.html">GridView</a></code></dt>
<dd>A view that shows items in
two-dimensional scrolling grid. For an example, see the Bookmarks app
widget.</dd> 
<dt><code><a href="../../../reference/android/widget/StackView.html">StackView</a></code></dt>
<dd>A
stacked card view (kind of like a rolodex), where the user can flick the  front
card up/down to see the previous/next card, respectively.  Examples include
the YouTube and Books app widgets. </dd> 
<dt><code><a href="../../../reference/android/widget/AdapterViewFlipper.html">AdapterViewFlipper</a></code></dt>
<dd>An adapter-backed simple
<code><a href="../../../reference/android/widget/ViewAnimator.html">ViewAnimator</a></code> that  animates between two or more views. Only one
child is shown at a time.  </dd>
</dl>

<p>As stated above, these collection views display collections backed by remote
data. This means that they use an <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code> to bind their
user interface to their data. An <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code> binds individual
items from a set of data into individual <code><a href="../../../reference/android/view/View.html">View</a></code> objects.
Because these collection views are backed by adapters, the Android framework
must include extra architecture to support their use in app widgets. In the
context of an app widget, the <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code> is replaced by a
<code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>,
which is simply a thin wrapper around  the <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code>
interface. 
 When
requested for a specific item in the collection, the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> creates
and returns the item for the collection as a <code><a href="../../../reference/android/widget/RemoteViews.html">RemoteViews</a></code>
object.
In order to include a collection view in your app widget, you
must implement <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> and <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>.</p>

<p> <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> is a service that allows a remote
adapter to request <code><a href="../../../reference/android/widget/RemoteViews.html">RemoteViews</a></code> objects. <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> is an
interface for an adapter between a collection view (such as <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>, <code><a href="../../../reference/android/widget/GridView.html">GridView</a></code>, and so on) and the
underlying data for that view. From the  <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a>, here is an example of the boilerplate code you use to implement 
this service and interface:
</p>

<pre>
public class StackWidgetService extends RemoteViewsService {
    &#64;Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {

//... include adapter-like methods here. See the StackView Widget sample.

}
</pre>

<h3 id="collection_sample">Sample application</h3>

<p>The code excerpts in this section are drawn from the <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a>:</p>

<p>
<img src="../../../resources/samples/images/StackWidget.png" alt="StackView
Widget" />
</p>

<p>This sample consists of a stack of 10 views, which  display the values
<code>&quot;0!&quot;</code> through <code>&quot;9!&quot;</code> The sample
app widget has these primary behaviors:</p> 

<ul>

  <li>The user can vertically fling the top view in the
app widget to display the next or previous view. This is a built-in StackView
behavior.</li> 

  <li>Without any user interaction, the app widget automatically advances
through
its views in sequence, like a slide show. This is due to the setting
<code>android:autoAdvanceViewId=&quot;@id/stack_view&quot;</code> in the
<code>res/xml/stackwidgetinfo.xml</code> file. This setting applies to the view
ID,
which in this case is the view ID of the stack view.</li>
  
  <li>If the user touches the top view, the app widget displays the <code><a href="../../../reference/android/widget/Toast.html">Toast</a></code> message &quot;Touched view <em>n</em>,&quot; where
<em>n</em> is the index (position) of the touched view. For more discussion of
how this is implemented, see  
<a href="#behavior">Adding behavior to individual items</a>.</li>

</ul>
<h3 id="implementing_collections">Implementing app widgets with collections</h3>

<p>To implement an App Widget with collections, you follow the same basic steps 
you would use to implement any app widget. The following sections  describe the
additional steps you need to perform to implement an App Widget with
collections.</p>

<h4>Manifest for app widgets with collections</h4>

<p> In addition to the requirements listed in <a href="#Manifest">Declaring an
App Widget in the Manifest</a>, to make it possible for App Widgets with
collections to bind to your <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code>, you must
declare the service in your manifest file with the permission <code><a href="../../../reference/android/Manifest.permission.html#BIND_REMOTEVIEWS">BIND_REMOTEVIEWS</a></code>. This prevents other applications
from freely accessing your app widget's data. For example, when creating an App
Widget that uses <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> to populate a
collection view, the manifest entry may look like this:</p>

<pre>&lt;service android:name=&quot;MyWidgetService&quot;
...
android:permission=&quot;android.permission.BIND_REMOTEVIEWS&quot; /&gt;</pre>

<p>The line <code>android:name=&quot;MyWidgetService&quot;</code>
refers to your subclass of <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code>. </p>

<h4>Layout for app widgets with collections</h4>

<p>The main requirement for your app widget layout XML file is that it
include one of the collection views: <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>,
<code><a href="../../../reference/android/widget/GridView.html">GridView</a></code>, <code><a href="../../../reference/android/widget/StackView.html">StackView</a></code>, or
<code><a href="../../../reference/android/widget/AdapterViewFlipper.html">AdapterViewFlipper</a></code>. Here is the
<code>widget_layout.xml</code> for
the <a href="../../../resources/samples/StackWidget/index.html">StackView
Widget sample</a>:</p>

<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;

&lt;FrameLayout xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;
    android:layout_width=&quot;match_parent&quot;
    android:layout_height=&quot;match_parent&quot;&gt;
    &lt;StackView xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;
        android:id=&quot;&#64;+id/stack_view&quot;
        android:layout_width=&quot;match_parent&quot;
        android:layout_height=&quot;match_parent&quot;
        android:gravity=&quot;center&quot;
        android:loopViews=&quot;true&quot; /&gt;
    &lt;TextView xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;
        android:id=&quot;&#64;+id/empty_view&quot;
        android:layout_width=&quot;match_parent&quot;
        android:layout_height=&quot;match_parent&quot;
        android:gravity=&quot;center&quot;
        android:background=&quot;&#64;drawable/widget_item_background&quot;
        android:textColor=&quot;#ffffff&quot;
        android:textStyle=&quot;bold&quot;
        android:text=&quot;&#64;string/empty_view_text&quot;
        android:textSize=&quot;20sp&quot; /&gt;
&lt;/FrameLayout&gt;</pre>

<p> Note that empty views must be siblings of the collection view for which the
empty view represents empty state. </p>

<p>In addition to the layout file for your entire app widget, you must create
another layout file that defines the layout for each item in the collection (for
example, a layout for each book in a collection of books). For example, the <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a> only has one layout file, <code>widget_item.xml</code>, since all
items use the same layout. But the <a
href="../../../resources/samples/WeatherListWidget/index.html">
WeatherListWidget sample</a> has two layout files:
<code>dark_widget_item.xml</code> and <code>light_widget_item.xml</code>.</p>



<h4 id="AppWidgetProvider-collections">AppWidgetProvider class for app widgets with collections</h4>

<p>As with a regular app widget, the bulk of your code in your <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> subclass typically goes in <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code>. The major difference in
your implementation for <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> when creating an app
widget with collections is that you must call <code><a href="../../../reference/android/widget/RemoteViews.html#setRemoteAdapter(int, android.content.Intent)">setRemoteAdapter()</a></code>. This tells the
collection view where to get its data. The <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> can then return your implementation of <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>, and
the widget can serve up the appropriate data. When you call this method, you
must pass an intent that  points to your implementation of <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> and the App Widget ID that specifies the app
widget to update.</p>


<p>For example, here's how the StackView Widget sample implements the <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[])">onUpdate()</a></code> callback method to set
the <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> as the remote adapter for the app widget
collection:</p>

<pre>public void onUpdate(Context context, AppWidgetManager appWidgetManager,
int[] appWidgetIds) {
    // update each of the app widgets with the remote adapter
    for (int i = 0; i &lt; appWidgetIds.length; ++i) {
        
        // Set up the intent that starts the StackViewService, which will
        // provide the views for this collection.
        Intent intent = new Intent(context, StackWidgetService.class);
        // Add the app widget ID to the intent extras.
        intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
        intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
        // Instantiate the RemoteViews object for the App Widget layout.
        RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
        // Set up the RemoteViews object to use a RemoteViews adapter. 
        // This adapter connects
        // to a RemoteViewsService  through the specified intent.
        // This is how you populate the data.
        rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent);
        
        // The empty view is displayed when the collection has no items. 
        // It should be in the same layout used to instantiate the RemoteViews
        // object above.
        rv.setEmptyView(R.id.stack_view, R.id.empty_view);

        //
        // Do additional processing specific to this app widget...
        //
        
        appWidgetManager.updateAppWidget(appWidgetIds[i], rv);   
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds);
}</pre>
            
<h4>RemoteViewsService class</h4>

<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Persisting data</h3>
   <p>You can’t rely on a single instance of your service, or any data it
contains, to persist. You should therefore not store any data in your <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> (unless it is static). If you want your
app widget’s data to persist, the best approach is to use a <code><a href="../../../reference/android/content/ContentProvider.html">ContentProvider</a></code> whose data persists beyond the process
lifecycle.</p> </div>
</div>

<p>As described above, your <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> subclass
provides the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> used to  populate the remote collection view.</p> 

<p>Specifically, you need to
perform these steps:</p>

<ol>
  <li>Subclass <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code>. <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> is the service through which
a remote adapter can request <code><a href="../../../reference/android/widget/RemoteViews.html">RemoteViews</a></code>.  </li>
  
  <li>In your <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code> subclass, include a
class that implements the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>
interface. <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> is an interface for an adapter between a remote collection
view (such as <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>, <code><a href="../../../reference/android/widget/GridView.html">GridView</a></code>,
and so on) and  the underlying data for that view.  Your implementation is
responsible for making a <code><a href="../../../reference/android/widget/RemoteViews.html">RemoteViews</a></code> object  for each
item in the data set. This interface is a thin wrapper around <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code>.</li>
</ol>

<p>The primary contents of the <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code>
implementation is its <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>,
described below.</p>

<h4>RemoteViewsFactory interface</h4>

<p>Your custom class that implements the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>
interface provides the app widget with the data for the items in its collection.
To
do this, it combines your app widget item XML layout file with a source of data.
This source of data could be anything from a database to a simple array. In the
<a href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a>, the data source is an array of <code>WidgetItems</code>. The <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>
functions as an adapter to glue the data to the remote collection view.</p>

<p>The two most important methods you need to implement for your

<code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>
subclass are 
<code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#onCreate()">onCreate()</a></code> and
<code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#getViewAt(int)">getViewAt()</a></code>
.</p> 

<p>The system calls <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#onCreate()">onCreate()</a></code> when
creating your factory for the first time. This is where you set up any
connections and/or cursors to your data source. For example, the <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a> uses <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#onCreate()">onCreate()</a></code> to
initialize an array of <code>WidgetItem</code> objects. When your app widget is
active, the system accesses these objects using their index position in the
array and the text they contain is displayed  </p>

<p>Here is an excerpt from the the <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget</a>
sample's 
<code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> implementation that shows portions of the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#onCreate()">onCreate()</a></code>
method:</p>

<pre>class StackRemoteViewsFactory implements
RemoteViewsService.RemoteViewsFactory {
    private static final int mCount = 10;
    private List&lt;WidgetItem&gt; mWidgetItems = new ArrayList&lt;WidgetItem&gt;();
    private Context mContext;
    private int mAppWidgetId;

    public StackRemoteViewsFactory(Context context, Intent intent) {
        mContext = context;
        mAppWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
    }

    public void onCreate() {
        // In onCreate() you setup any connections / cursors to your data source. Heavy lifting,
        // for example downloading or creating content etc, should be deferred to onDataSetChanged()
        // or getViewAt(). Taking more than 20 seconds in this call will result in an ANR.
        for (int i = 0; i &lt; mCount; i++) {
            mWidgetItems.add(new WidgetItem(i + &quot;!&quot;));
        }
        ...
    }
...</pre>

<p>The <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> method <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#getViewAt(int)">getViewAt()</a></code>
returns a <code><a href="../../../reference/android/widget/RemoteViews.html">RemoteViews</a></code> object corresponding to the data at
the specified <code>position</code> in the data set. Here is an excerpt from 
the <a
href="http://developer.android.com/resources/samples/StackWidget/index.html">
StackView Widget</a> sample's <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>
implementation:</p>

<pre>public RemoteViews getViewAt(int position) {
   
    // Construct a remote views item based on the app widget item XML file, 
    // and set the text based on the position.
    RemoteViews rv = new RemoteViews(mContext.getPackageName(), R.layout.widget_item);
    rv.setTextViewText(R.id.widget_item, mWidgetItems.get(position).text);

    ...
    // Return the remote views object.
    return rv;
}</pre>

<h4 id="behavior">Adding behavior to individual items</h4>

<p>The above sections show you how to bind your data to your app widget
collection. But what if you want to add dynamic behavior to the individual items
in your collection view?</p> 

<p> As described in <a href="#AppWidgetProvider">Using the AppWidgetProvider
Class</a>, you  normally use <code><a href="../../../reference/android/widget/RemoteViews.html#setOnClickPendingIntent(int, android.app.PendingIntent)">setOnClickPendingIntent()</a></code> to set an object's click
behavior&mdash;such as to cause a button to launch an <code><a href="../../../reference/android/app/Activity.html">Activity</a></code>. But this approach is not allowed for child views in an
individual collection item (to clarify, you could use <code><a href="../../../reference/android/widget/RemoteViews.html#setOnClickPendingIntent(int, android.app.PendingIntent)">setOnClickPendingIntent()</a></code> to set up a global button
in the Gmail app widget that launches the app, for example, but not on the
individual list items). Instead, to add click behavior to individual items in a
collection, you  use <code><a href="../../../reference/android/widget/RemoteViews.html#setOnClickFillInIntent(int, android.content.Intent)">setOnClickFillInIntent()</a></code>. This entails setting up up a pending intent template
for your collection view, and then setting a fill-in intent on each item in the
collection via your <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>.</p> 
<p>This section uses the <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a> to describe how to add behavior to individual items. In the <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a>, if the user touches the top view, the app widget displays the <code><a href="../../../reference/android/widget/Toast.html">Toast</a></code> message &quot;Touched view <em>n</em>,&quot; where
<em>n</em> is the index (position) of the touched view. This is how it
works:</p>

<ul>
  <li>The <code>StackWidgetProvider</code> (an <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> subclass) creates a pending intent that has
a custom action called <code>TOAST_ACTION</code>.</li>
  <li>When the user touches a view, the intent is fired and it broadcasts
<code>TOAST_ACTION</code>.</li>
  
  <li>This broadcast is intercepted by the <code>StackWidgetProvider</code>'s
<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onReceive(android.content.Context, android.content.Intent)">onReceive()</a></code> method, and the app widget displays the
<code><a href="../../../reference/android/widget/Toast.html">Toast</a></code> message for the touched view. The data for the collection
items is provided by the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>, via
the <code><a href="../../../reference/android/widget/RemoteViewsService.html">RemoteViewsService</a></code>.</li>
</ul>

<p class="note"><strong>Note:</strong> The <a
href="../../../resources/samples/StackWidget/index.html">StackView Widget
sample</a> uses a broadcast, but typically an app widget would simply launch an
activity in a scenario like this one.</p>

<h5>Setting up the pending intent template</h5> 

<p>The <code>StackWidgetProvider</code> (<code><a href="../../../reference/android/appwidget/AppWidgetProvider.html">AppWidgetProvider</a></code> subclass) sets up a pending intent.
Individuals items of a collection cannot set up their own pending intents.
Instead, the collection as a whole sets up a pending intent template, and the
individual items set a fill-in intent to create unique behavior on an
item-by-item
basis.</p> 

<p>This class  also receives the broadcast that is sent when the user touches a
view. It processes this event in its <code><a href="../../../reference/android/appwidget/AppWidgetProvider.html#onReceive(android.content.Context, android.content.Intent)">onReceive()</a></code> method. If the intent's action is
<code>TOAST_ACTION</code>, the app widget displays a <code><a href="../../../reference/android/widget/Toast.html">Toast</a></code>
message for the current view.</p>

<pre>public class StackWidgetProvider extends AppWidgetProvider {
    public static final String TOAST_ACTION = &quot;com.example.android.stackwidget.TOAST_ACTION&quot;;
    public static final String EXTRA_ITEM = &quot;com.example.android.stackwidget.EXTRA_ITEM&quot;;

    ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks to see whether the intent's action is TOAST_ACTION. If it is, the app widget 
    // displays a Toast message for the current item.
    &#64;Override
    public void onReceive(Context context, Intent intent) {
        AppWidgetManager mgr = AppWidgetManager.getInstance(context);
        if (intent.getAction().equals(TOAST_ACTION)) {
            int appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
            int viewIndex = intent.getIntExtra(EXTRA_ITEM, 0);
            Toast.makeText(context, &quot;Touched view &quot; + viewIndex, Toast.LENGTH_SHORT).show();
        }
        super.onReceive(context, intent);
    }
    
    &#64;Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // update each of the app widgets with the remote adapter
        for (int i = 0; i &lt; appWidgetIds.length; ++i) {
    
            // Sets up the intent that points to the StackViewService that will
            // provide the views for this collection.
            Intent intent = new Intent(context, StackWidgetService.class);
            intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            // When intents are compared, the extras are ignored, so we need to embed the extras
            // into the data so that the extras will not be ignored.
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
            rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent);
    
            // The empty view is displayed when the collection has no items. It should be a sibling
            // of the collection view.
            rv.setEmptyView(R.id.stack_view, R.id.empty_view);

            // This section makes it possible for items to have individualized behavior.
            // It does this by setting up a pending intent template. Individuals items of a collection
            // cannot set up their own pending intents. Instead, the collection as a whole sets
            // up a pending intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            Intent toastIntent = new Intent(context, StackWidgetProvider.class);
            // Set the action for the intent.
            // When the user touches a particular view, it will have the effect of
            // broadcasting TOAST_ACTION.
            toastIntent.setAction(StackWidgetProvider.TOAST_ACTION);
            toastIntent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            PendingIntent toastPendingIntent = PendingIntent.getBroadcast(context, 0, toastIntent,
                PendingIntent.FLAG_UPDATE_CURRENT);
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent);
            
            appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
        }
    super.onUpdate(context, appWidgetManager, appWidgetIds);
    }
}</pre>
            
<h5><strong>Setting the fill-in Intent</strong></h5>

<p>Your <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> must set a fill-in intent on each item in the collection.
This makes it possible to distinguish the individual on-click action of a given
item. The fill-in intent is then combined with the <code><a href="../../../reference/android/app/PendingIntent.html">PendingIntent</a></code> template in order to determine the final intent that
will be executed when the item is clicked. </p>

<pre>
public class StackWidgetService extends RemoteViewsService {
    &#64;Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int mCount = 10;
    private List&lt;WidgetItem&gt; mWidgetItems = new ArrayList&lt;WidgetItem&gt;();
    private Context mContext;
    private int mAppWidgetId;

    public StackRemoteViewsFactory(Context context, Intent intent) {
        mContext = context;
        mAppWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
    }

    // Initialize the data set.
        public void onCreate() {
            // In onCreate() you set up any connections / cursors to your data source. Heavy lifting,
            // for example downloading or creating content etc, should be deferred to onDataSetChanged()
            // or getViewAt(). Taking more than 20 seconds in this call will result in an ANR.
            for (int i = 0; i &lt; mCount; i++) {
                mWidgetItems.add(new WidgetItem(i + &quot;!&quot;));
            }
           ...
        }
        ...
    
        // Given the position (index) of a WidgetItem in the array, use the item's text value in 
        // combination with the app widget item XML file to construct a RemoteViews object.
        public RemoteViews getViewAt(int position) {
            // position will always range from 0 to getCount() - 1.
    
            // Construct a RemoteViews item based on the app widget item XML file, and set the
            // text based on the position.
            RemoteViews rv = new RemoteViews(mContext.getPackageName(), R.layout.widget_item);
            rv.setTextViewText(R.id.widget_item, mWidgetItems.get(position).text);
    
            // Next, set a fill-intent, which will be used to fill in the pending intent template
            // that is set on the collection view in StackWidgetProvider.
            Bundle extras = new Bundle();
            extras.putInt(StackWidgetProvider.EXTRA_ITEM, position);
            Intent fillInIntent = new Intent();
            fillInIntent.putExtras(extras);
            // Make it possible to distinguish the individual on-click
            // action of a given item
            rv.setOnClickFillInIntent(R.id.widget_item, fillInIntent);
        
            ...
        
            // Return the RemoteViews object.
            return rv;
        }
    ...
    }</pre>

<h3 id="fresh">Keeping Collection Data Fresh</h3>

<p>The following figure illustrates the flow that occurs in an App Widget that
uses
collections when updates occur. It shows how the App Widget code interacts with
the  <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>, and how you can trigger updates:</p>

<img src="../../../images/appwidget_collections.png" alt="" />

<p>One feature of App Widgets that use collections is the ability to provide
users with up-to-date content. For example, consider the Android 3.0 Gmail
app widget, which provides users with a snapshot of their inbox. To make this
possible, you need to be able to trigger your <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code> and
collection view to fetch and display new data. You achieve this with the <code><a href="../../../reference/android/appwidget/AppWidgetManager.html">AppWidgetManager</a></code> call <code><a href="../../../reference/android/appwidget/AppWidgetManager.html#notifyAppWidgetViewDataChanged(int, int)">notifyAppWidgetViewDataChanged()</a></code>. This call results in a callback to your
<code>RemoteViewsFactory</code>’s <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#onDataSetChanged()">onDataSetChanged()</a></code> method, which gives you the opportunity to fetch any new
data. Note that you can perform
processing-intensive operations synchronously within the  <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#onDataSetChanged()">onDataSetChanged()</a></code> callback. You are guaranteed that this call will be
completed before the metadata or view data is fetched from the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html">RemoteViewsFactory</a></code>. In
addition, you can perform processing-intensive operations within the <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#getViewAt(int)">getViewAt()</a></code>
method. If this call takes a long time, the loading view (specified by the
<code>RemoteViewsFactory</code>’s  <code><a href="../../../reference/android/widget/RemoteViewsService.RemoteViewsFactory.html#getLoadingView()">getLoadingView()</a></code> method)
will be displayed in the corresponding position of the collection view until it
returns.</p>



    </div>

  <a href="#top" style="float:right">&uarr; Go to top</a>
  
  </div>

<div id="footer">


  <div id="copyright">
    
  Except as noted, this content is licensed under <a
  href="http://www.apache.org/licenses/LICENSE-2.0">Apache 2.0</a>. 
  For details and restrictions, see the <a href="../../../license.html">
  Content License</a>.
  </div>
  <div id="build_info">
    
  Android 4.0&nbsp;r1 - 17 Oct 2011 18:17

  </div>

  <div id="footerlinks">
    
  <p>
    <a href="http://www.android.com/terms.html">Site Terms of Service</a> -
    <a href="http://www.android.com/privacy.html">Privacy Policy</a> -
    <a href="http://www.android.com/branding.html">Brand Guidelines</a>
  </p>
  </div>

</div> <!-- end footer -->

</div><!-- end doc-content -->

</div> <!-- end body-content --> 

<script type="text/javascript">
init(); /* initialize android-developer-docs.js */
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-5831155-1");
pageTracker._trackPageview();
</script>

</body>
</html>



